Markdown w/ Frontmatter Agent Parser #16094

sehoon38 · 2026-01-07T21:44:29Z

Summary

Migrate to use md w/ Frontmatter instead of toml files.

Details

Markdown is increasingly becoming the industry standard. Transitioning to this format ensures consistency and simplifies the developer experience.

replace toml-loader with agent Loader
Flattened prompt structures to remove nested fields. system_prompt and query have been moved to the top level. Since Frontmatter relies on YAML-style indentation, flattening these fields makes them significantly easier for users to edit.
Enabled prompt writing within the Markdown body. This provides a much better experience for drafting long-form prompts compared to multi-line strings in TOML.

Related Issues

Fixes #15968

How to Validate

Create a directory: mkdir -p .gemini/agents
Create a file .gemini/agents/test-agent.md

---
name: sample-agent
description: A sample agent for testing the markdown parser.
display_name: Sample Markdown Agent
tools:
  - list_directory
  - read_file
model:
  model: gemini-2.0-flash-exp
  temperature: 0.7
query: how are you?
system_prompt: |
  hello how are you
---

Also testing multi-remote agents

create another file .gemini/agents/test-remote-agents.md

---
- kind: remote
  name: remote-agent-double-1
  description: First of two agents
  agent_card_url: https://example.com/agent-2
- kind: remote
  name: remote-agent-double-2
  description: Second of two agents
  agent_card_url: https://example.com/agent-3
---

Run npm run preflight to ensure all tests pass.
Verify that the agent is discovered by checking logs in debug mode.

Pre-Merge Checklist

- Add FrontmatterRemoteAgentDefinition and Zod schema for remote agents - Support 'kind: remote' and 'agent_card_url' in markdown frontmatter - Allow optional body for remote agents in parser - Update loader tests to cover remote agent scenarios

- Flatten localAgentSchema to support top-level 'system_prompt' and 'query' in frontmatter - Remove nested 'prompts' object from schema and interface - Clean up excessive blank lines in loader.ts - Update tests to reflect schema changes and verify top-level prompt fields

gemini-code-assist · 2026-01-07T21:44:48Z

Summary of Changes

Hello @sehoon38, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant refactoring of how agents are defined and loaded within the system. By transitioning from TOML to Markdown files with YAML frontmatter, the change aims to streamline the agent definition process, allowing for more intuitive system prompt specification directly within the Markdown body. This update enhances the flexibility and maintainability of agent configurations, ensuring a more robust and user-friendly approach to managing agent definitions.

Highlights

Migration to Markdown for Agent Definitions: Agent definitions are now parsed from Markdown files with YAML frontmatter, replacing the previous TOML format.
Renamed Loader Module: The toml-loader.ts file has been renamed to loader.ts to reflect the change in parsing format.
Updated Parsing Logic: The parsing mechanism now uses js-yaml to extract frontmatter and can derive the system prompt from the Markdown body if not explicitly defined in the frontmatter.
File Scanning Update: The loadAgentsFromDirectory function now specifically targets .md files for agent definitions, ignoring other file types and those prefixed with an underscore.
Comprehensive Testing: A new test suite (loader.test.ts) has been added to thoroughly validate the new Markdown parsing and loading functionalities, replacing the deprecated TOML loader tests.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

github-actions · 2026-01-07T21:47:11Z

Size Change: +290 B (0%)

Total Size: 22.3 MB

ℹ️ View Unchanged

Filename	Size	Change
`./bundle/gemini.js`	22.3 MB	+290 B (0%)
`./bundle/sandbox-macos-permissive-closed.sb`	1.03 kB	0 B
`./bundle/sandbox-macos-permissive-open.sb`	890 B	0 B
`./bundle/sandbox-macos-permissive-proxied.sb`	1.31 kB	0 B
`./bundle/sandbox-macos-restrictive-closed.sb`	3.29 kB	0 B
`./bundle/sandbox-macos-restrictive-open.sb`	3.36 kB	0 B
`./bundle/sandbox-macos-restrictive-proxied.sb`	3.56 kB	0 B

_{compressed-size-action}

gemini-code-assist

Code Review

This pull request refactors the agent definition loader, migrating from TOML files to Markdown with YAML frontmatter, involving the replacement of the TOML parser with "js-yaml" and updates to data structures, validation schemas, and file loading logic. However, a critical insecure deserialization vulnerability was identified due to the use of yaml.load() on untrusted file content, which can lead to Remote Code Execution. A high-severity Server-Side Request Forgery (SSRF) vulnerability was also found, as the agent_card_url is not properly sanitized. Additionally, a high-severity correctness bug was identified. Immediate remediation is recommended for these issues before merging.

packages/core/src/agents/agentLoader.ts

- Rename packages/core/src/agents/loader.ts to agentLoader.ts - Rename packages/core/src/agents/loader.test.ts to agentLoader.test.ts - Update imports in registry.ts and registry.test.ts - Add parsing for remote agents list in markdown frontmatter - Update tests to verify single and multiple remote agents parsing

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

abhipatel12

Left a few thoughts. Let me know what you think!

packages/core/src/agents/agentLoader.ts

packages/core/src/agents/agentLoader.test.ts

packages/core/src/agents/agentLoader.ts

abhipatel12

Looks great!

abhipatel12 · 2026-01-12T16:18:14Z

packages/core/src/skills/skillLoader.ts

 }

-const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)/;
+export const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)/;


nit: we don't have to do it in this PR, but let's either fix or create a small follow-up issue to move this to a shared const file so that we're not importing loader logic from a skills file.

adamfweidman · 2026-01-12T16:28:00Z

Change the wording in cli-help-agent.ts to reflect change from toml to md (confirm full demo flow doc still works)

sehoon38 · 2026-01-12T16:41:05Z

Change the wording in cli-help-agent.ts to reflect change from toml to md (confirm full demo flow doc still works)

#16409 hasn't been merged yet, do you want to update this PR with the wording here?

gemini-code-assist · 2026-01-12T16:41:19Z

Hi @sehoon38, thanks for asking! I recommend going ahead and updating the wording in cli-help-agent.ts in this pull request.

The change from TOML to Markdown for agent definitions is a core part of this PR, and updating the help text to reflect this change will ensure consistency for users immediately. If google-gemini/gemini-cli/pull/16409 introduces further changes to the help text, those can be addressed in a follow-up PR once it's merged.

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

sehoon38 added 2 commits January 7, 2026 13:34

sehoon38 changed the title ~~Sehoon/agent parser~~ Markdown w/ Frontmatter Agent Parser Jan 7, 2026

gemini-code-assist bot reviewed Jan 7, 2026

View reviewed changes

packages/core/src/agents/agentLoader.ts Show resolved Hide resolved

packages/core/src/agents/agentLoader.ts Outdated Show resolved Hide resolved

jacob314 added the status/need-issue Pull requests that need to have an associated issue. label Jan 7, 2026

gemini-cli bot added priority/p1 Important and should be addressed in the near term. and removed status/need-issue Pull requests that need to have an associated issue. labels Jan 7, 2026

sehoon38 and others added 2 commits January 7, 2026 21:19

Apply suggestion from @gemini-code-assist[bot]

c8c7446

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

sehoon38 marked this pull request as ready for review January 8, 2026 17:23

sehoon38 requested a review from a team as a code owner January 8, 2026 17:23

gemini-cli bot added the area/agent Issues related to Core Agent, Tools, Memory, Sub-Agents, Hooks, Agent Quality label Jan 8, 2026

remove system_prompt from frontmatter field

66566b3

abhipatel12 self-requested a review January 9, 2026 17:31

abhipatel12 reviewed Jan 9, 2026

View reviewed changes

make frontmatter fields all top levels

a4a88a0

sehoon38 mentioned this pull request Jan 12, 2026

fix(core): ensure sub-agent schema and prompt refresh during runtime #16409

Merged

18 tasks

abhipatel12 approved these changes Jan 12, 2026

View reviewed changes

abhipatel12 added this pull request to the merge queue Jan 12, 2026

Merged via the queue into main with commit 7b7f2fc Jan 12, 2026
26 checks passed

abhipatel12 deleted the sehoon/agent_parser branch January 12, 2026 16:40

theerud pushed a commit to theerud/gemini-cli that referenced this pull request Jan 12, 2026

Markdown w/ Frontmatter Agent Parser (google-gemini#16094)

57fae73

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Markdown w/ Frontmatter Agent Parser #16094

Markdown w/ Frontmatter Agent Parser #16094

Conversation

sehoon38 commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details

Related Issues

How to Validate

Pre-Merge Checklist

Uh oh!

gemini-code-assist bot commented Jan 7, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

github-actions bot commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

abhipatel12 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

abhipatel12 left a comment

Choose a reason for hiding this comment

Uh oh!

abhipatel12 Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

adamfweidman commented Jan 12, 2026

Uh oh!

Uh oh!

sehoon38 commented Jan 12, 2026

Uh oh!

gemini-code-assist bot commented Jan 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sehoon38 commented Jan 7, 2026 •

edited

Loading

github-actions bot commented Jan 7, 2026 •

edited

Loading